Shareware Grab Bag/Shareware Grab Bag.iso/003/snap.arc/SNAP.HLP

Text File | 1986-04-28 | 16.5 KB | 357 lines

2.1    System Name
Enter the name of the system you wish to document.  This name is used
in the program file heading and on the source code listings. If you do
not choose to write file headings, you may omit this field.
!
2.2    Author
Enter the name of the system author.  This name is used in the
program file heading and on the source code listings.  If you do not
choose to write file headings, you may omit this field.
!
2.3    Copyright Holder
Enter the name of the copyright holder, or leave blank if the author
holds the copyright.  This name is used in the program file heading
and on the source code listings.  If you do not choose to write file
headings, you may omit this field.
!
2.4    Copyright Date
Enter the copyright date.  This date is used in the program file
heading and the source code listing.  If you choose not to write file
headings, you may omit this field.
!
2.5    Top File Name
Input the first filename you wish to document.  Do not enter a drive
designation or a path.  File extensions are optional.  If you wish
to document an entire dBASE system, this file should be the "top"
file in the system.

If this field is blank or if the filename you enter does not exist,
SNAP! will exit to DOS.
!
2.6   Path for Source Code Files
Enter the path for your system's source code files.   Your entry
should begin with a backslash ('\') but should not end with one.  For
example, if your programs are in a directory called DBASE\SOURCE, you
would enter the following:

   Path to source code files: \DBASE\SOURCE

Snap! will execute a CHDIR command to make this directory the default
directory.
!
2.7   Path for Output Files
Enter the path for SNAP! documentation.   Your entry should begin
with a backslash ('\') but should not end with one.  For example, if
you want output routed to a directory called DBASE\OUTPUT, you would
enter the following:

   Path to write output files to: \DBASE\OUTPUT
!
2.8   Path for SNAP! Overlays
Enter the path for SNAP! overlay files, help files and keywords.  If
SNAP! is in the current directory, simply press the enter key.
Otherwise, enter the path to the directory in which SNAP! resides.
Your entry should begin with a backslash ('\') but should not end
with one.  For example, if SNAP! is in a directory called DBASE\SNAP,
you would enter the following:

   Path to SNAP! Overlays: \DBASE\SNAP
!
2.9    Search Tree?
Enter a "Y" here to search all programs in the tree below the
filename you entered above.  If you enter a "N", SNAP! will only
document the specific file you enter.
!
2.10   dBASE III Format?
Enter a "Y" if your system is written in dBASE III.  Otherwise, enter
a "N".  dBASE II and dBASE III use different syntax and different
formats for database and index files.
!
3.1    Write Documentation File Headings?
Answer "Y" or "N" depending on whether you want to write file
headings on each program file documented.  The file heading is a
series of comments documenting the filename, system name, and
copyright notice, in addition to a list of files that call the
program, files the program calls, and databases, index files, format
files, report forms and memory files used.  SNAP! writes the
file heading directly onto your program file (but backs up your
original file if your source and output paths are the same).
!
3.2    Indent Program Source Code?
Choose "Y" to indent code underneath control structures (DO WHILE,
IF, CASE etc.). If you choose to indent your code, one tab character
will be inserted for each control statement nesting level.

This option also scans your source code for unmatched control
structures (e.g., IFs not matched with ENDIFs) and reports any
discrepancies.
!
3.3   Capitalize dBASE Key Words?
Choose "Y" to capitalize all occurrences of key words found in the
DB3WORDS.TXT or DB2WORDS.TXT file, the original version of which
contains all dBASE key words.  You may add extra words to be
capitalized to this file, or temporarily "comment out" key words
from the file by prefacing them with an asterisk.  Also, SNAP! will
recognize valid 4-character abbreviations of key words (e.g., PICT
will be recognized as an abbreviation of PICTURE).
!
3.4    Write Program Tree Structure?
Choose "Y" to display and echo to a file a diagram of the system tree
structure, showing which programs call which other programs, and
which programs use which databases.  The diagram also indicates which
"programs" are dBASE III procedures, but it does not try to diagram
program files called from procedures.
!
3.5    Write List of Files Used in System
Choose "Y" to display and echo to a file a list of all files used in
the system.  This report shows programs, databases, index files,
report forms, format files, memory files, and procedures.  You might
use such a report to identify all the files in a subdirectory that
your application uses.
!
3.6    Write Index File Summary?
Choose "Y" to display and echo to a file a summary of index files
used in the system.  SNAP! watches for references to indexes
within your programs and will prepare a report showing the index file
name, the fields on which it is indexed, and the program files that
use it.
!
3.7    Write Database Summary and Data Dictionary?
Choose "Y" to display and echo to a file a database summary and data
dictionary, showing each field in the system and the databases
containing it.  The data dictionary also highlights the links among
your databases.  In addition to the data dictionary, this option
displays a list of each database used in the system, the database
structure, and a list of program files which use the database.
!
3.8    Write Format File Summary?
Choose "Y" to display and echo to a file a summary of format files
used in the system.  SNAP! watches for references to format files
within your programs and will prepare a report showing the format
file name and the program files that use it.
!
3.9    Write Report Form Summary?
Choose "Y" to display and echo to a file a summary of report forms
used in the system.  SNAP! watches for references to report forms
within your programs and will prepare a report showing the report
form name and the program files that use it.
!
3.10   Write Procedure Summary?
Choose "Y" to display and echo to a file a summary of procedures used
in the system.  SNAP! watches for references to procedures within
your programs and will prepare a report showing the procedure name,
the individual procedures it contains and the program files that use
it.
!
3.11    Write Variable Cross Reference?
Choose "Y" to display and echo to a file a cross reference of all
words in the system that are not key words, quoted strings or numeric
constants.  This report provides system-wide documentation of each
program and program line that references a memory variable, file
name, field, and so forth.  You can also 1) include selected key
words in this report by prefacing them with an asterisk in the key
word file, or 2) exclude memory variables by adding them temporarily
to the key word file.  SNAP! is limited to 512 individual words and a
maximum of 128 references to an individual word.
!
3.12    Print dBASE Source Code?
Choose "Y" to print a nicely-formatted listing of the source code for
all programs in the system.  You can select line width, margin, and
so on.  SNAP! will print a listing for each program, showing the
program name, author, copyright notice, system, date and time
printed and the page number.  In addition, SNAP! will wrap any
lines that exceed the line widths you specify, and at your option
will print line numbers.  The line numbers may be useful for
examining variable references displayed by the cross reference option
or for tracking down error messages.
!
3.13   Ignore Drive Designations?
Choose "Y" to ignore drive designations when looking for program
files. This option is useful if your program tests for the existence
of files on various drives and makes a decision based on the results.
If you choose not to ignore drive designations, SNAP! will attempt
to find the program files on the specified drive.  Depending on the
equipment you have installed, DOS may prompt you to insert a disk in
drive B.  This DOS message usually messes up the SNAP! screen.
!
3.14   Key Word File Name
Input the filename containing a list of keywords to be capitalized
(and not included in the cross-reference listing).  This file should
contain one keyword per line.  The program operates faster if the
words are sorted, but will accept them in any order.
!
3.15    Tree Structure File Name
Input the filename for the tree diagram to be written to.  If you
choose not to display the tree, this field is ignored.
!
3.16    File List File Name
Input the filename for the file list to be written to.  If you
choose not to display the file list, this field is ignored.
!
3.17    Index Summary File Name
Input the filename for the index summary to be written to.  If you
choose not to display the index summary, this field is ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.18    Data Dictionary File Name
Input the filename for the data dictionary to be written to.  If you
choose not to display the data dictionary, this field is ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.19    Format Summary File Name
Input the filename for the format file summary to be written to.  If
you choose not to display the format file summary, this field is
ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.20    Report Form Summary File Name
Input the filename for the report form summary to be written to.  If
you choose not to display the report form summary, this field is
ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.21    Procedure Summary File Name
Input the filename for the procedure summary to be written to.  If
you choose not to display the procedure summary, this field is
ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.22    Cross Reference File Name
Input the filename for the cross reference to be written to.  If you
choose not to display the cross reference, this field is ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
4.1   Cross-reference Public Variables
Your response here determines whether dBASE III public variables will
be included in the cross-reference report.  If you answer this
question 'Y' and the other questions 'N', then only public variables
will appear on the cross-reference report.
!
4.2   Cross-reference Other Variables and Tokens
The cross-reference report normally includes all "things" in your
source code that are not either:
   Comments                     Numeric constants
   Key words                    Punctuation
   Quoted strings

Accordingly, file names, field names, and so on will appear in the
cross-reference listing.  If you wish to restrict the report to
public variables only, you can respond 'N' to this and subsequent
questions.
!
4.3   Cross-reference dBASE III Key Words
Your response determines whether key words will be included in
the cross-reference report.  If you respond 'Y' then all words in the
key words file will be referenced on the report.  For example, you
might select this option to see where you used the REPLACE verb.
For large dBASE systems, you will probably exceed the number of
allowable references to such commonly-used key words as SAY, STORE,
TO, and perhaps others. If so, SNAP! will display a warning message
("Too many references to SAY") and continue processing your files.
Any excess references are discarded and do not appear on the report.
!
4.4   Cross-reference Numeric Constants
Your response determines whether numbers used in your system will
appear on the cross-reference report.  Under normal circumstances,
they will probably only get in the way, but you may occasionally want
to see where you used a particular constant, especially if you later
need to change it.
!
5.1   Cross-reference Variables and Tokens
The cross-reference report normally includes all "things" in your
source code that are not either:
   Comments                     Numeric constants
   Key words                    Punctuation
   Quoted strings

Accordingly, variable names, file names, field names, and so on will
appear in the cross-reference listing.  Respond 'N' to exclude them
from the report.
!
5.2   Cross-reference dBASE II Key Words
Your response determines whether key words will be included in
the cross-reference report.  If you respond 'Y' then all words in the
key words file will be referenced on the report.  For example, you
might select this option to see where you used the REPLACE verb.
For large dBASE systems, you will probably exceed the number of
allowable references to such commonly-used key words as SAY, STORE,
TO, and perhaps others. If so, SNAP! will display a warning message
("Too many references to SAY") and continue processing your files.
Any excess references are discarded and do not appear on the report.
!
5.3   Cross-reference Numeric Constants
Your response determines whether numbers used in your system will
appear on the cross-reference report.  Under normal circumstances,
they will probably only get in the way, but you may occasionally want
to see where you used a particular constant, especially if you later
need to change it.
!
6.1   Line Width
Input a line width between 40 and 255.  The standard line width of
most printers using 8.5 x 11 inch paper is 80, but you can change it
by using wide paper and entering the appropriate setup codes for your
printer.  The line width you enter should be the total number of
characters your printer can print across a line.  The actual length
of printed source code lines will be reduced by the left and right
margins you set below.  Source code lines longer than the line width
you specify will be wrapped to the next line.
!
6.2   Page Length
Input a page length greater than or equal to 0.  If you enter 0, the
program assumes continuous form paper and will not write page
headings except on the first page.  Page length must also be larger
than your top and bottom margins.
!
6.3   Top Margin
Enter a number greater than 3 and smaller than your page length.  The
first three lines are used to print a heading on each page.
!
6.4   Bottom Margin
Enter a number greater than or equal to 0.  This many lines will be
left blank at the bottom of each page.
!
6.5   Left Margin
Enter a number greater than 0 and less than your line width.  Line
numbers (or source code if you elect not to print line numbers) will
begin this many spaces from the left edge of the paper.  A left
margin of 12 usually leaves room for 3-hole binder punches.
!
6.6   Right Margin
Enter a number greater than 0 and less than your line width.  This
many spaces will remain between your source code and the right
edge of the paper.
!
6.7   Spaces per Tab
Enter a number between 1 and 12.  Each tab character in your source
code will be converted to this many spaces as the source code is
printed.  The source code file will be unaffected--the expansion is
done for printing purposes only.  Tab expansions of 3 or 4 make the
code easy to follow without causing it to march off the right side of
the page.
!
6.8   Print Line Numbers?
Choose "Y" to print line numbers next to each line of source code or
"N" to suppress them.  Line numbers are useful references for
following up on error messages or for using the variable
cross-reference report.
!
6.9   Printer Setup Codes
Enter setup codes for your printer.  The default codes shift an Epson
(and many other printers) into compressed print.  The format for
setup codes is three-digit decimal numbers separated by slashes (/).
This field is always optional.
!